Managing INI Files "What is fame? An empty bubble; gold? A transient shining trouble" Solitude, James Grainger, 1721-1766 Introduction Look at almost any hard drive nowadays and you will find an assortment of INI files. Initialization files are text files that contain the variables related to an application or other program information. Although INI files were popularized by Windows applications, they are equally valuable to text-mode applications. An INI file is simply a structured text file designed for storing strings and numbers. An INI file consists of one or more sections with related entries (keynames) within the section. Following is an example of an .INI file. [DIRECTORIES] Programs=C:\ACCOUNTS Data=C:\ACCOUNTS\FILES Temp=C:\ [EXTENSIONS] Ext1=DBF; database files Ext2=DAT Ext3=RES To take advantage of Gold's INI support, you need to understand the various components in an INI file. An INI file is composed of sections, keys, values and comments. The Section The name (header) of a section. The enclosing brackets ([ ]) are required, and the left bracket must be in the leftmost column on the screen. In the above example, there are two sections: DIRECTORIES and EXTENSIONS. The Entry Name The name of an entry, which can consist of any combination of letters and digits. The entry name is usually followed by an '=' character. In the above example, the DIRECTORIES section has three entries: Programs, Data and Temp. The Value The value of each entry, which can be an integer, a string or a quoted string. This is the text which lies to the right of the equals sign. In the above example, the Programs entry has the value C:\ACCOUNTS. The Comments Some entries include brief comments below the header or on the same line as an entry. You can include comments anywhere in an .INI file by prefacing the comment with a semicolon (;). Notice the comment database files in the above example. INI File Management INI files are not renowned for their speed! Gold provides two methods of creating and managing INI files. If you are only accessing small amounts of data, the standard access methods should suffice. However, if the application makes repeated calls to an INI file, then the buffered routines will offer improved performance. Standard Routines Listed below are the standard routines for saving and loading values in an INI file. GetIniString( Default, Section, Entry, FName: string ): string; Returns a string representing the data found using the defined parameters. GetIniInt( Default, Section, Entry, FName: string ): integer; Returns an integer representing the data found using the defined parameters. GetIniLong( Default, Section, Entry, FName: string ): longint; Returns a longint representing the data found using the defined parameters. GetIniReal( Default, Section, Entry, FName: string ): real; Returns a real value representing the data found using the defined parameters. WriteIniString( Section, Entry, EntryVal, FName: string ): integer; Updates the data defined by the passed parameters if both section and entry are found. If either is not located the entry and/or section are created accordingly. If the INI file does not exist, one will be created. If any value other than zero is returned, the write did not take place. GetIniSection( var SL: SingleLL; Section, FName: string): integer; Reads an entire section into the passed singly linked list. A zero value indicates a successful read. Most of the above routines contain four common parameters: Default, Section, Entry and Filename. The default parameter is what the function will return to the application if the section or entry is not located. The section parameter is the name of the section, without the brackets ([ ]). The entry parameter is the entry name of the data to be accessed. It is followed immediately by an equals sign (=). The filename parameter is the name of the .INI file to search in. Refer to the demo files DEMINI1.PAS and DEMINI2.PAS to see the standard INI file routines in action. Buffered Routines Each time a standard INI routine (discussed above) is called, disk access is required. The buffered routines provide an alternative method to improve performance when a lot of INI calls are required. This method loads the entire INI file onto the heap, where it remains until you remove it. Since some INI files can be extremely large, as a developer you must concern yourself with the available amount of heap space. You should first compare the amount of available heap space to the size of the INI file to be loaded. Gold uses an internal list for the buffered routines. Remember that any change made to an INI entry while using the buffered routines must be saved to disk using SaveIni to actually be retained. LoadIni(LFileName: string): integer; Loads an entire INI file into memory using the available heap space. A zero value indicates success. UnLoadIni; Removes the previously loaded INI file from memory releasing the heap space. PutIniString( Section, Entry, EntryVal:string ): integer; Modifies the value of the specfied entry. SaveIni( LFileName: pathstr;OverWrite:boolean ): integer; Writes the contents of the INI buffer back to disk for future use. If OverWrite is set to false, a backup (.BAK) of the INI file is created prior to the actual saving of the data being held in memory, otherwise the original file is overwritten. ReadIniString( Default,Section,Entry:string ): string; Returns a string representing the data found by the defined parameters. ReadIniInt( Default,Section,Entry:string ): integer; Returns an integer value representing the data found using the defined parameters. ReadIniLong( Default,Section,Entry:string ): longint; Returns a longint value representing the data found using the defined parameters. ReadIniReal( Default,Section,Entry:string ): real; Returns a real value representing the data found using the defined parameters. ReadIniSection( var SL:SingleLL; Section:string): integer; Loads an entire section into the specified list. A zero value indicates a successful read. Error Codes LastIniError: integer; Returns the last error generated by the INI unit. INI Colors Just to resolve your concerns, there are no colors to be supported in the INI unit.